/**
 * $version:  0.1 
 * $Date: 2011-01-21 
 *
 * Copyright (C) 2010-2011 Jawa Software. All rights reserved.
 *
 */

package org.jawa.user;

import java.util.Collection;
import java.util.List;

import org.jawa.core.exception.AlreadyExistsException;
import org.jawa.core.exception.UserNotFoundException;


/**
 * 用户操作接口.
 * 
 */
public interface UserProvider {

	/**
	 * 根据 userId 加载用户。
	 * 
	 * @param userId
	 *            userId
	 * @return 用户.
	 * 
	 * @throws 假如用户没有找到抛出
	 *             UserNotFoundException.
	 * 
	 */
	public User loadUserByUserid(Long userId) throws UserNotFoundException;

	/**
	 * 根据 username 加载用户。
	 * 
	 * @param username
	 *            username
	 * @return 用户.
	 * 
	 * @throws 假如用户没有找到抛出
	 *             UserNotFoundException.
	 * 
	 */
	public User loadUserByUsername(String username) throws UserNotFoundException;

	/**
	 * 创建用户.
	 * 
	 * @param User
	 *            用户信息.
	 * @return 创建好的用户.
	 * @throws UserAlreadyExistsException
	 *             用户名称已存在.
	 * @throws Exception 
	 */
	public User createUser(User user) throws AlreadyExistsException, Exception;

	/**
	 * 删除用户。
	 * 
	 * @param userID
	 *            要删除用户的 userID.
	 * 
	 */
	public void deleteUser(Long userID);

	/**
	 * 返回总的用户数.
	 * 
	 * @return 总的用户数.
	 * 
	 */
	public int getUserCount();

	/**
	 * 返回系統中所有用戶的 userId.
	 * 
	 * @return 不可以修改的系統中所有用户的 userId集合.
	 * 
	 */
	public Collection<Long> getUserIds();

	/**
	 * 返回所有的用户（用户集合）,{@link UserCollection} 集合用于协助这个返回结果，他需要一个Long[] userid
	 * 的数组，在实际需要数据的时候再{@link UserManager#getUser()}进行查询实际数据.
	 * 
	 * @return 不可以修改的用户集合.
	 */
	public Collection<User> getUsers();

	/**
	 * 返回所有的用户（用户集合）,{@link UserCollection} 集合用于协助这个返回结果，他需要一个Long[] userid
	 * 的数组，在实际需要数据的时候再{@link UserManager#getUser()}进行查询实际数据.
	 * 
	 * @param startIndex
	 *            起始索引.
	 * @param numResults
	 *            要显示的用户数据数量.
	 * @return 不可以修改的用户集合.
	 * 
	 */
	public Collection<User> getUsers(int startIndex, int numResults);

	/**
	 * 根据查询条件查询符合条件的的用户信息。
	 * 
	 * @param fieldQuerys
	 *            要查询的条件信息.
	 * 
	 * @return 查询到的用户信息结果.
	 * 
	 */
	public Collection<User> findUsers(List<String> fields, List<String> querys);

	/**
	 * 根据查询条件查询符合条件的的用户信息。
	 * 
	 * @param fieldQuerys
	 *            要查询的条件信息.
	 * @param startIndex
	 *            查询结果起始索引.
	 * @param numResults
	 *            要显示的用户数据数量.
	 * @return 查询到的用户信息结果.
	 * 
	 */
	public Collection<User> findUsers(List<String> fields, List<String> querys,
			int startIndex, int numResults);

}